HAL I2S initialization and configuration functions migration

The goal of this page is to show how to migrate the initialization sequence using STM32CubeMX2:

  • Open STM32CubeMX2 I2S configuration panel.

  • Configure the SW layer HAL.

  • Configure the I2S main features.

  • Configure the additional I2S features if needed.

  • Configure the I2S GPIO pins.

  • Configure the I2S DMA(s) if the application requires to use the I2S in DMA mode.

  • Configure the NVIC if the application requires the I2S to be used in IT mode.

  • Generate the code.

HAL I2S configuration panel

Create a new project with STM32CubeMX2, start by enabling the SPI instance as I2S as shown in this example with the selected SPI1, then start the initialization and the main configuration.

Project configuration panel

HAL I2S main features configuration

Configure the I2S main features.

I2S main feature configuration

HAL I2S advanced features configuration

Configure the I2S advanced features.

I2S advanced feature configuration

GPIO configuration

Configure GPIO pins.

I2S GPIO configuration

DMA configuration

Configure the DMA for data reception as needed.

DMA TX configuration

I2S DMA TX configuration

DMA RX configuration

I2S DMA RX configuration

Note

STM32CubeMX2 does not expose an I2S DMA RX configuration for this generated I2S project.

NVIC configuration

Configure the NVIC in case of an interrupt.

I2S NVIC configuration

Generated I2S initialization and de-initialization sequences

The I2S initialization sequence is generated in the mx_spi1_init function in mx_spi1.c file under $YOUR_PROJECT_NAME$/$YOUR_PROJECT_NAME$_SW/generated/STM32Cube_CodeGen.

Related concepts:

STM32CubeMX2 Generated : I2S initialization and de-initialization sequences

Topic

Code Snippet HAL1

Code Snippet HAL2

Handle declaration 

I2S_HandleTypeDef hi2s1;

static hal_i2s_handle_t hSPI1;

Initialization and configuration sequence 

static void MX_I2S1_Init(void)
{
  hi2s1.Instance = SPI1;
  hi2s1.Init.Mode = I2S_MODE_MASTER_TX;
  hi2s1.Init.Standard = I2S_STANDARD_PHILIPS;
  hi2s1.Init.DataFormat = I2S_DATAFORMAT_16B;
  hi2s1.Init.MCLKOutput = I2S_MCLKOUTPUT_DISABLE;
  hi2s1.Init.AudioFreq = I2S_AUDIOFREQ_8K;
  hi2s1.Init.CPOL = I2S_CPOL_LOW;
  hi2s1.Init.ClockSource = I2S_CLOCK_PLL;
  hi2s1.Init.FullDuplexMode = I2S_FULLDUPLEXMODE_DISABLE;
  if (HAL_I2S_Init(&hi2s1) != HAL_OK)
  {
    Error_Handler();
  }
}

static void MX_GPIO_Init(void)
{
  /* GPIO Ports Clock Enable */
  __HAL_RCC_GPIOA_CLK_ENABLE();
}

void HAL_I2S_MspInit(I2S_HandleTypeDef* hi2s)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  RCC_PeriphCLKInitTypeDef PeriphClkInitStruct = {0};
  if(hi2s->Instance==SPI1)
  {
     PeriphClkInitStruct.PeriphClockSelection = RCC_PERIPHCLK_I2S;
     PeriphClkInitStruct.PLLI2S.PLLI2SN = 192;
     PeriphClkInitStruct.PLLI2S.PLLI2SM = 16;
     PeriphClkInitStruct.PLLI2S.PLLI2SR = 2;
     if (HAL_RCCEx_PeriphCLKConfig(&PeriphClkInitStruct) != HAL_OK)
     {
       Error_Handler();
     }

     /* Peripheral clock enable */
     __HAL_RCC_SPI1_CLK_ENABLE();

     __HAL_RCC_GPIOA_CLK_ENABLE();

     GPIO_InitStruct.Pin = GPIO_PIN_4|GPIO_PIN_5|GPIO_PIN_7;
     GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
     GPIO_InitStruct.Pull = GPIO_NOPULL;
     GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
     GPIO_InitStruct.Alternate = GPIO_AF5_SPI1;
     HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

     /* I2S1 interrupt Init */
     HAL_NVIC_SetPriority(SPI1_IRQn, 0, 0);
     HAL_NVIC_EnableIRQ(SPI1_IRQn);
   }
 }

hal_i2s_handle_t *mx_spi1_init(void)
{
  hal_i2s_slave_config_t i2s_config;

  if (HAL_I2S_Init(&hSPI1, HAL_I2S1) != HAL_OK)
  {
    return NULL;
  }

  HAL_RCC_SPI1_EnableClock();

  if (HAL_RCC_SPI1_SetKernelClkSource(HAL_RCC_SPI1_CLK_SRC_PCLK2) != HAL_OK)
  {
    return NULL;
  }

  i2s_config.mode = HAL_I2S_MODE_SLAVE_TX;
  i2s_config.standard = HAL_I2S_STANDARD_PHILIPS;
  i2s_config.data_format = HAL_I2S_DATA_FORMAT_16_BIT;
  i2s_config.clock_polarity = HAL_I2S_CLOCK_POLARITY_LOW;
  i2s_config.bit_order = HAL_I2S_MSB_FIRST;

  if (HAL_I2S_SLAVE_SetConfig(&hSPI1, &i2s_config) != HAL_OK)
  {
    return NULL;
  }

  if (HAL_I2S_SetFifoThreshold(&hSPI1, HAL_I2S_FIFO_THRESHOLD_1_DATA) != HAL_OK)
  {
    return NULL;
  }

  HAL_RCC_GPIOA_EnableClock();

  hal_gpio_config_t  gpio_config;

  gpio_config.mode        = HAL_GPIO_MODE_ALTERNATE;
  gpio_config.output_type = HAL_GPIO_OUTPUT_PUSHPULL;
  gpio_config.pull        = HAL_GPIO_PULL_NO;
  gpio_config.speed       = HAL_GPIO_SPEED_FREQ_LOW;
  gpio_config.alternate   = HAL_GPIO_AF_5;
  HAL_GPIO_Init(HAL_GPIOA, HAL_GPIO_PIN_5 | HAL_GPIO_PIN_15 | HAL_GPIO_PIN_6 | HAL_GPIO_PIN_7, &gpio_config);

  if (HAL_RCC_SPI1_SetKernelClkSource(HAL_RCC_SPI1_CLK_SRC_PCLK2) != HAL_OK)
  {
    return NULL;
  }

  /* Enable the interruption for I2S */
  HAL_CORTEX_NVIC_SetPriority(SPI1_IRQn, HAL_CORTEX_NVIC_PREEMP_PRIORITY_0, HAL_CORTEX_NVIC_SUB_PRIORITY_0);
  HAL_CORTEX_NVIC_EnableIRQ(SPI1_IRQn);

  return &hSPI1;
}

Deinitialization sequence 

void MX_I2S_DeInit(void)
{
  if (HAL_I2S_DeInit(&hi2s1) != HAL_OK)
  {
    Error_Handler();
  }
}

void HAL_I2S_MspDeInit(I2S_HandleTypeDef* hi2s)
{
  if(hi2s->Instance==SPI1)
  {
    /* Peripheral clock disable */
    __HAL_RCC_SPI1_CLK_DISABLE();

    HAL_GPIO_DeInit(GPIOA, GPIO_PIN_4|GPIO_PIN_5|GPIO_PIN_7);

    /* I2S1 interrupt DeInit */
    HAL_NVIC_DisableIRQ(SPI1_IRQn);
   }
 }

void mx_spi1_deinit(void)
{
  /* Disable the interruption for I2S */
  HAL_CORTEX_NVIC_DisableIRQ(SPI1_IRQn);

  (void)HAL_I2S_DeInit(&hSPI1);

  HAL_RCC_SPI1_Reset();

  HAL_RCC_SPI1_DisableClock();

  /* De-initialize all GPIO pins associated with SPI1 */
  HAL_GPIO_DeInit(HAL_GPIOA, HAL_GPIO_PIN_5 | HAL_GPIO_PIN_6 | HAL_GPIO_PIN_7 | HAL_GPIO_PIN_15);
}

IRQ handle function 

void SPI1_IRQHandler(void)
{
  HAL_I2S_IRQHandler(&hi2s1);
}

void SPI1_IRQHandler(void)
{
  HAL_I2S_IRQHandler(&hSPI1);
}